/**
 * Copyright (c) 2008, EffCode, www.effcode.com
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without modification, 
 * are permitted provided that the following conditions are met:
 * 
 * Redistributions of source code must retain the above copyright notice, this list 
 * of conditions and the following disclaimer. 
 * Redistributions in binary form must reproduce the above copyright notice, this list 
 * of conditions and the following disclaimer in the documentation and/or other materials
 * provided with the distribution. 
 * Neither the name of the EffCode nor the names of its contributors may be used 
 * to endorse or promote products derived from this software without specific prior written 
 * permission. 
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY 
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 
 * THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 
 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR 
 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package org.effdom;

/**
 * The <code>Attr</code> class represents the data in the EffCode protocol.
 * The <code>Attr</code> belongs to an <code>Element</code>. The
 * <code>Attr</code> holds some kind of data and is identified by an ID. The
 * ID must be unique for the within the elements attribute context.
 * 
 * @author <a href="mailto:mattias@effcode.com">Mattias Jonsson</a>
 * 
 * @see Element
 */
public interface Attr extends Node {

    /**
     * The method returns the data hold by the <code>Attr</code> represented
     * as an string. Primitives like int and long are converted to a string
     * using <code>String.valueOf method</code>. If the <code>Attr</code>
     * contains a binary values a string is created using the binary value as
     * argument to constructor, new String(bytes).
     * 
     * @return the value hold by the <code>Attr</code> represented as a
     *         <code>String</code> or Null if the <code>Attr</code> doesn't
     *         contain any data.
     * 
     * @throws IllegalStateException
     *             an <code>IllegalStateException</code> is thrown if the
     *             <code>Attr</code> is unable to return the <code>Attr</code>
     *             value.
     */
    public String value() throws IllegalStateException;

    /**
     * The method returns the data hold by the <code>Attr</code> as a byte
     * array. The method is typically used for binary data. It is not supposed
     * to use for any other kind of data. If the <code>Attr</code> doesn't
     * support to return the current hold data represented as a byte array an
     * <code>IllegalStateException</code> will be raised.
     * 
     * @return the value hold by the <code>Attr</code> represented as a byte
     *         array or Null if the <code>Attr</code> doesn't contain any
     *         data.
     * 
     * @throws IllegalStateException
     *             an <code>IllegalStateException</code> is thrown if the
     *             <code>Attr</code> is unable to return the <code>Attr</code>
     *             value. This may happen if the <code>Attr</code>
     *             implementation can't return the current hold data as a byte
     *             array.
     */
    public byte[] valueAsByteArray() throws IllegalStateException;

    /**
     * The method returns the data hold by the <code>Attr</code> as a
     * <code>int</code>. If the <code>Attr</code> contains an number
     * greater than Integer.MAX or less than Integer.MIN or if the value is not
     * a number an <code>IllegalStateException</code> will be raised.
     * 
     * @return the value hold by the <code>Attr</code> represented as an
     *         <code>int</code>. Default value is 0.
     * 
     * @throws IllegalStateException
     *             an <code>IllegalStateException</code> is thrown if the
     *             <code>Attr</code> is unable to return the <code>Attr</code>
     *             value. This may happen if the <code>Attr</code>
     *             implementation can't return the current hold data as an
     *             <code>int</code>.
     */
    public int valueAsInt() throws IllegalStateException;

    /**
     * The method returns the data hold by the <code>Attr</code> as a
     * <code>long</code>. If the <code>Attr</code> contains an value that
     * is not a number an <code>IllegalStateException</code> will be raised.
     * 
     * @return the value hold by the <code>Attr</code> represented as an
     *         <code>long</code>. Default value is 0.
     * 
     * @throws IllegalStateException
     *             an <code>IllegalStateException</code> is thrown if the
     *             <code>Attr</code> is unable to return the <code>Attr</code>
     *             value. This may happen if the <code>Attr</code>
     *             implementation can't return the current hold data as an
     *             <code>long</code>.
     */
    public long valueAsLong() throws IllegalStateException;

}
